Node / ReticulumProjects / MeshChatX.git / files / docs / en / rns-link-api.md

Displaying Raw • View rendered • Download

Tc9d1d9# Generic RNS Link API

MeshChatX exposes a generic Reticulum Link transport over the main WebSocket (Ta5d6ff`/ws`) so external apps and plugins can open links, run request/response exchanges, send packets, and tear links down without going through NomadNet-specific helpers.

This is the surface used by microReticulum management consoles that treat MeshChatX as an RNS transport.

Tc9d1d9## Auth

When password auth is enabled, all Ta5d6ff`rns.link.*` client messages require an authenticated session (same rule as other WebSocket mutators).

Tc9d1d9## Client → server

| Ta5d6ff`type` | Fields | Behavior |

| ------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |

| Ta5d6ff`rns.link.open` | Ta5d6ff`destination_hash` (hex), Ta5d6ff`aspect` (dot-separated), Ta5d6ff`request_id`, Ta5d6ff`auto_identify?` | Open or reuse a cached link to Ta5d6ff`(aspect, destination_hash)`. Streams Ta5d6ff`phase` then Ta5d6ff`success` / Ta5d6ff`failure`. |

| Ta5d6ff`rns.link.identify` | Ta5d6ff`destination_hash`, Ta5d6ff`aspect`, Ta5d6ff`request_id` | Call Ta5d6ff`link.identify(local_identity)` on the cached link. |

| Ta5d6ff`rns.link.request` | Ta5d6ff`destination_hash`, Ta5d6ff`aspect`, Ta5d6ff`path`, Ta5d6ff`request_id`, Ta5d6ff`data_b64?`, Ta5d6ff`timeout?` | Ensure the link is open, then Ta5d6ff`link.request(path, data=…)`. Ta5d6ff`data_b64` / reply Ta5d6ff`body_b64` are msgpack payloads, base64-encoded. |

| Ta5d6ff`rns.link.send` | Ta5d6ff`destination_hash`, Ta5d6ff`aspect`, Ta5d6ff`payload_b64`, Ta5d6ff`request_id` | Send a raw packet on the cached link. |

| Ta5d6ff`rns.link.close` | Ta5d6ff`destination_hash`, Ta5d6ff`aspect`, Ta5d6ff`request_id` | Teardown and uncache the link. |

Ta5d6ff`aspect` is split on Ta5d6ff`.` into RNS app name + sub-aspects (for example Ta5d6ff`microrn.mgmt`).

Long-running Ta5d6ff`open` / Ta5d6ff`request` work is tracked per WebSocket client and cancelled when that client disconnects.

Tc9d1d9## Server → client

Per-`request_id` replies reuse the same Ta5d6ff`type` with Ta5d6ff`status` of Ta5d6ff`phase`, Ta5d6ff`progress`, Ta5d6ff`success`, or Ta5d6ff`failure`.

Broadcast events:

| Ta5d6ff`type` | Ta5d6ff`event` | Notes |

| ---------------- | ----------------- | ---------------------- |

| Ta5d6ff`rns.link.event` | Ta5d6ff`packet_received` | Includes Ta5d6ff`payload_b64` |

| Ta5d6ff`rns.link.event` | Ta5d6ff`link_closed` | Cached link removed |

Tc9d1d9## Plugin capabilities

Plugins that declare the matching Ta5d6ff`permissions.managers` entries can call the same transport through Ta5d6ff`POST /api/v1/plugins/{id}/invoke` with Ta5d6ff`method: "callManager"`:

Tff7b72- Ta5d6ff`rnsLink.open`

Tff7b72- Ta5d6ff`rnsLink.identify`

Tff7b72- Ta5d6ff`rnsLink.request`

Tff7b72- Ta5d6ff`rnsLink.send`

Tff7b72- Ta5d6ff`rnsLink.close`

Subscribe to async link traffic with Ta5d6ff`permissions.hooks: ["rns.link.event"]`. Events arrive as Ta5d6ff`plugin.event` WebSocket frames with Ta5d6ff`event: "rns.link.event"`.

Example manifest fragment:

Ta5d6ff```Ta5d6ffjson

Tb4b4b4{

Tff7b72"permissions"Tb4b4b4: Tb4b4b4{

Tff7b72"hooks"Tb4b4b4: Tb4b4b4[Ta5d6ff"rns.link.event"Tb4b4b4],

Tff7b72"managers"Tb4b4b4: Tb4b4b4[Ta5d6ff"rnsLink.open"Tb4b4b4, Ta5d6ff"rnsLink.identify"Tb4b4b4, Ta5d6ff"rnsLink.request"Tb4b4b4, Ta5d6ff"rnsLink.send"Tb4b4b4, Ta5d6ff"rnsLink.close"Tb4b4b4],

Tff7b72"storage"Tb4b4b4: Ta5d6ff"isolated"Tb4b4b4,

Tff7b72"network"Tb4b4b4: Ta5d6ff"none"

Tb4b4b4}

Tb4b4b4}

Ta5d6ff```

Tc9d1d9## Implementation

Tff7b72- Ta5d6ff`meshchatx/src/backend/rns_link_manager.py` — link cache, open/identify/request/send/close

Tff7b72- Ta5d6ff`meshchatx/meshchat.py` — WebSocket dispatch and per-client task tracking

Tff7b72- Ta5d6ff`meshchatx/src/backend/plugin_manager.py` — capability wrappers and hook fan-out

Tc9d1d9## Related

Tff7b72- **Plugins** in Tools docs for install/enable flow

Tff7b72- **Architecture** for the plugin runtime overview